Ankorstore Public API (1.0.0)

ℹ️ This guide walks you through the essential steps to make your first API call and understand the basic integration flow.

To access the API you need a client_id and client_secret. Generate these by logging in at ankorstore.com and creating a new application in the Integrations area of your account.

The API uses OAuth2 Client Credentials. Exchange your credentials for an access token:

[POST] https://www.ankorstore.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=*

You receive a Bearer token valid for 1 hour:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

Include it in all subsequent requests:

Authorization: Bearer {access_token}
Accept: application/vnd.api+json

See Authentication for rate limits and troubleshooting.

Confirm your token works by fetching your user configuration:

[GET] /api/v1/me/config

A successful 200 response means you are authenticated and ready to go.

What you do next depends on your integration goal. Here are the most common starting points:

Sync your catalog

Fetch your products and their variants:

[GET] /api/v1/products

[GET] /api/v1/products/{product}?include=productVariants

Update stock for a product variant:

[PATCH] /api/v1/product-variants/{productVariant}/stock

For bulk product operations (import, update, delete), see Catalog Integrations.

Process orders

List your orders via Master Orders, including the underlying order details:

[GET] /api/v1/master-orders?include=internalOrder,externalOrder

Accept a new order and manage the shipping flow:

[POST] /api/v1/orders/{order}/-actions/transition

See Ordering for the full order lifecycle and status transitions.

Set up webhooks

Rather than polling for new orders, subscribe to real-time notifications:

[POST] /api/v1/webhook-subscriptions

See Webhook Subscription for available events and signature verification.

• How to work with API — JSON:API conventions, pagination, filters, and includes
• Integration Scenarios — Common integration patterns and recommended approaches
• Available APIs — Full overview of all API capabilities

ℹ️ This section provides an overview of the general concepts and conventions used throughout the API. Also, you can find some best practices and recommendations with examples, which will help you to get started with the API.

API Specification/Schema

This API follows the Ankorstore API Specification which is based on the JSON:API specification. Please give our specification a thorough read to understand how our request and response formats work.

Interacting with API

It is recommended that you only use the resource list endpoint to retrieve newly created resource or to get the status of top level information (e.g. such as new orders or if you have been paid yet). Please use the single resource retrieval endpoint if you wish to fetch more information about each resource.

Headers

When making any request apart from retrieving an access token, the header Accept: application/vnd.api+json is required. When sending JSON within the body of a request the header Content-Type: application/vnd.api+json is also required.

🔗 Learn more about JSON:API media types

Resource Data

In every response, the actual resource data can be found in the root level object data, this will either be an array or an object, depending on if its list based or not.

🔗 Learn more about JSON:API document structure

Includes

Resources may have the ability to include data from other relations in the same request. For example, when fetching a single order you may include the retailer, the order's order items etc.

?include=retailer,orderItems.productOption.product

Includes also support nested relationships, so you can pull every order items specific product variant and base product etc.

🔗 Learn more about JSON:API includes

Pagination

Ankorstore uses cursor based pagination. In the root level object for pagination supported endpoints you will find a meta object containing pagination information:

  type: object
  description: Meta
  properties:
    meta:
      type: object
      description: Meta with Pagination Details
      properties:
        page:
          description: Cursor pagination details
          type: object
          properties:
            from:
              type: string
            to:
              type: string
            hasMore:
              type: boolean
            perPage:
              type: integer

As an example:

{
  "meta": {
    "page": {
      "from": "63e9bacd-0288-4cf1-81ab-b34270c7f68a",
      "to": "747a1dcd-decc-4f8d-a9a9-61ff4d33d92e",
      "hasMore": true,
      "perPage": 15
    }
  }
}

You may manually construct the pagination query parameters yourself using page[limit] with page[before] or page[after] depending on which direction you wish to iterate over.

The response will also provide pagination links, so you do not need to construct these yourself:

  type: object
  description: Links
  properties:
    links:
      description: Pagination navigation links. If a link does not exist then you cannot paginate any further in that direction.
      type: object
      properties:
        first:
          type: string
          format: url
        next:
          type: string
          format: url
        prev:
          type: string
          format: url

As an example:

{
  "links": {
    "first": "https://www.ankorstore.com/api/v1/orders?include=&page%5Blimit%5D=15",
    "next": "https://www.ankorstore.com/api/v1/orders?include=&page%5Bafter%5D=1189606a-139e-4b4e-917c-b0c992498bad&page%5Blimit%5D=15",
    "prev": "https://www.ankorstore.com/api/v1/orders?include=&page%5Bbefore%5D=e04e17bb-9e70-4ecd-a8f5-4417d45b872c&page%5Blimit%5D=15"
  }
}

🔗 Learn more about JSON:API pagination

Filters

An endpoint that supports filters requires each listed filter to be wrapped in a filter object. E.g. you may wish to only retrieve new orders:

?filter[status]=ankor_confirmed

You may also chain filters as well:

?filter[status]=ankor_confirmed&filter[retailer]=1189606a-572e-4b4e-88da-b0c992498bad

🔗 Learn more about JSON:API filters

API Versioning

The Ankorstore API uses URL-based versioning. The current version is v1, reflected in all endpoint paths (e.g., /api/v1/products).

Backward compatibility guarantees:

Within a major version, you can rely on the following:

• Existing endpoints remain available at the same paths
• Existing response fields continue to be returned with the same types
• Existing request parameters continue to be accepted
• Existing enum values are not removed

What may change without a new version:

• New optional fields added to response objects
• New optional query parameters or filter options
• New enum values added to existing fields
• New endpoints added under the same version prefix
• New webhook event types

Your integration should handle these additive changes gracefully. For example, use lenient JSON parsing that ignores unknown fields rather than failing on them.

Breaking changes:

If we need to make a breaking change (removing a field, changing a type, removing an endpoint), we follow this process:

1. The affected endpoint or field is marked as deprecated in the API documentation
2. A migration guide is published in the Changelog describing the change and the recommended alternative
3. Deprecated features remain functional for a transition period before removal
4. Removal is announced in advance via the changelog

Subscribe to changelog updates and monitor deprecation notices in the API documentation to stay ahead of any changes.

ℹ️ The Ankorstore API uses OAuth2 authentication, in order to get a client_id and a client_secret please, login at https://www.ankorstore.com/ and generate a new application in the integrations area of your account.

To generate a token pass in your client_id and client_secret:

{
  "method": "post",
  "headers": {
    "accept": "application/json",
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "baseUrl": "https://www.ankorstore.com",
  "url": "/oauth/token",
  "body": "grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope=*"
}

You will receive an access_token:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9<...>"
}

This access token has an expiry, in which you will receive an 401 Unauthenticated response. To generate a new one you can re-call the /oauth/token endpoint described above.

To authenticate with every other endpoint pass in the header Authorization: Bearer {token}. You can test if your token is working with this endpoint (this is a not a JSON:API based endpoint):

{
  "method": "get",
  "headers": {
    "accept": "application/json",
    "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9<...>"
  },
  "baseUrl": "https://www.ankorstore.com",
  "url": "/api/v1/me"
}

If successful you will receive a 200 response:

{
  "data": {
    "type": "user",
    "id": 1234,
    "email": "api@ankorstore.com",
    "first_name": "Test",
    "last_name": "Account",
    "created_at": "2020-01-28T11:26:35+00:00",
    "updated_at": "2022-03-15T15:23:09+00:00"
  }
}

Rate Limiting

When authenticated (passing a valid bearer token), the rate limits are:

• 600 requests per minute
• 24000 per hour
• 288000 per day

Meaning you could make a consistent 200 requests per minute, every minute, all day.

Or you could burst at up to 600 requests per minute for 40 minutes of an hour, for 12 hours of a day.

When unauthenticated for endpoints that do not require authentication the rates are:

• 120 requests per minute
• 4800 requests per hour
• 57600 requests per day

Api responses have the following headers to help you track and manage the rate limits:

• X-RateLimit-Remaining: The number of request remaining before encountering a 429 Too Many Requests error.
• X-RateLimit-Limit: The number of requests allowed by the current window.

If you exceed these rate limits then an error status code of 429 Too Many Requests will be returned, you will also receive the following headers:

• Retry-After: The number of seconds before more attempts become available, and you could try again.
• X-RateLimit-Reset: A timestamp for when more attempts become available, and you could try again, specified as seconds-since-epoch.

The special exception to these limits the authentication endpoint /oauth/token which is limited to 60 requests per hour. You should not need to authenticate more than this, if you do please get in contact with us.

Token Refresh Strategy

Access tokens expire after 3600 seconds (1 hour). To maintain uninterrupted API access, implement a proactive token refresh strategy:

Recommended approach:

1. Store the token expiry time — When you receive an access token, calculate the expiry timestamp using expires_in and store it alongside the token.
2. Refresh before expiry — Request a new token 5–10 minutes before the current token expires, rather than waiting for a 401 response. This prevents downtime in long-running integrations.
3. Handle 401 gracefully — If you do receive a 401 Unauthorized, immediately request a new token and retry the failed request once. Do not retry multiple times without re-authenticating.

Example token refresh logic (pseudocode):

let accessToken = null;
let tokenExpiresAt = null;

async function getToken() {
  const now = Date.now() / 1000; // Current Unix timestamp

  // If token is still valid for at least 5 minutes, reuse it
  if (accessToken && tokenExpiresAt && tokenExpiresAt - now > 300) {
    return accessToken;
  }

  // Otherwise, fetch a new token
  const response = await fetch('https://www.ankorstore.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: 'grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope=*'
  });

  const data = await response.json();
  accessToken = data.access_token;
  tokenExpiresAt = now + data.expires_in;

  return accessToken;
}

Avoid: Do not request a new token for every API call. This wastes resources and will quickly hit the /oauth/token rate limit of 60 requests per hour.

Security Best Practices

Protect your credentials:

• Never commit credentials to version control — Use environment variables or a secrets manager to store client_id and client_secret. Do not hardcode them in your source code.
• Rotate credentials regularly — Periodically generate new API credentials in the integrations area and phase out old ones.
• Restrict access — Only grant API credentials to systems and team members that need them. Treat client_secret with the same care as a password.

Secure token storage:

• Store tokens in memory — For server-side integrations, keep the access token in memory rather than persisting it to disk or a database. Tokens expire after 1 hour, so there is little value in long-term storage.
• Do not expose tokens to clients — Never send access tokens to browsers or mobile apps. API credentials are intended for server-to-server communication only.

Use HTTPS:

• All API requests must use HTTPS. The Ankorstore API will reject requests made over unencrypted HTTP.
• Ensure your webhook endpoint also uses HTTPS and a valid TLS certificate. See Webhook Subscription for signature verification requirements.

Monitor for anomalies:

• Log all API authentication attempts and monitor for unexpected patterns (e.g., sudden spikes in 401 responses or token refresh requests).
• If you suspect your credentials have been compromised, immediately revoke them in the integrations area and generate new ones.

ℹ️ The Ankorstore platform exposes several APIs. This page provides an overview of all available API groups and their capabilities.

The core API for managing your brand on the Ankorstore marketplace.

API Group	Audience	Description
General	All	Platform configuration and currency exchange rates
User	All	User and platform configuration (currency, country, CDN)
Catalog	Brands	Manage products, product variants, stock levels, and pricing
Catalog Integrations	Brands	Batch product import, update, and delete operations
Ordering	Brands	Manage master orders, internal orders, and external orders
Shipping	Brands	Get shipping quotes, confirm quotes, and schedule pickups
Fulfillment	Brands	Track fulfillments, manage replenishments, check fulfillable stock, and estimate costs
OrderPay	Brands	Create and manage orders for your own customers with integrated payment processing
Webhooks	All	Subscribe to real-time event notifications for orders, shipments, and more
Testing	All	Generate test orders and data in the sandbox environment

A dedicated API for advanced stock and inventory management. ASTRAL provides detailed stock visibility that goes beyond the core Catalog stock endpoints.

API Group	Description
State	Query current stock quantities by product variant, location, and status (available, reserved, onHand)
Movements	View stock movement history — postings (individual movements) and transactions (grouped movements with context)
Locations	List available stock locations (warehouses, brand locations)

ASTRAL is useful when you need to:

• Track stock across multiple locations (your own warehouse and Ankorstore fulfillment centers)
• Audit stock movements and understand what caused changes (orders, replenishments, adjustments)
• Monitor lot-level inventory with expiry and sell-by dates

ℹ️ This section describes common integration scenarios and the recommended API endpoints for each.

Catalog Synchronization (ERP / PIM)

Sync your product catalog and stock levels between your internal systems and Ankorstore.

Recommended approach

1. Initial catalog import — Use Catalog Integrations to batch-import products via the operations API. This handles create, update, and delete in bulk with async processing and callback notifications.
2. Ongoing stock sync — Keep stock levels in sync by updating product variant stock via PATCH /api/v1/product-variants/{productVariant}/stock whenever your inventory changes. For detailed stock visibility across locations, use the ASTRAL Stock State endpoint.
3. Price updates — Update product variant prices via PATCH /api/v1/product-variants/{productVariant}/prices.

Key endpoints

Endpoint	Purpose
POST /api/v1/catalog/integrations/operations	Create batch product operations
PATCH /api/v1/product-variants/{id}/stock	Update stock for a single variant
PATCH /api/v1/product-variants/{id}/prices	Update prices for a single variant
GET /api/v1/products	List your products

Order Management (ERP / OMS)

Integrate order processing with your order management system.

Recommended approach

1. Receive new orders — Subscribe to the order.brand_confirmed webhook event to receive instant notifications when new orders arrive, instead of polling.
2. Fetch order details — Retrieve the full order with GET /api/v1/master-orders/{id}?include=internalOrder to get all order lines, amounts, and shipping address.
3. Process the order — Transition the order through its lifecycle: confirm, ship, and track via the order and shipping endpoints.
4. Sync back to your systems — Use the order reference and masterOrderId fields to match Ankorstore orders with records in your OMS.

Key endpoints

Endpoint	Purpose
GET /api/v1/master-orders	List all orders with pagination
GET /api/v1/master-orders/{id}	Get a single order with includes
POST /api/v1/orders/{order}/-actions/transition	Accept/reject an order
POST /api/v1/orders/{order}/shipping-quotes	Get shipping quotes
POST /api/v1/shipping-quotes/{quote}/confirm	Confirm a shipping quote
POST /api/v1/webhook-subscriptions	Subscribe to order events

Order event webhooks

Event	When it fires
order.brand_confirmed	A new order is confirmed and ready for processing
order.shipped	The order has been shipped
order.received	The retailer has confirmed receipt
order.brand_paid	Payment has been transferred to the brand
order.cancelled	The order has been cancelled

Fulfillment Center Integration

Manage inventory at Ankorstore Fulfillment Centers and track fulfillments.

Recommended approach

1. Send inventory — Create replenishments via POST /api/v1/fulfillment/replenishments to declare incoming stock, then update the status to confirmed when ready.
2. Monitor stock — Check fulfillable stock with GET /api/v1/fulfillment/fulfillable and lot-level inventory with GET /api/v1/fulfillment/lots. For detailed multi-location stock data, use the ASTRAL API.
3. Track fulfillments — When orders are fulfilled, track their progress via GET /api/v1/fulfillment/orders/{id}?include=statusUpdates.
4. Estimate costs — Before committing to fulfillment, get cost estimates via POST /api/v1/fulfillment/costs/order.

Key endpoints

Endpoint	Purpose
POST /api/v1/fulfillment/replenishments	Declare incoming stock
GET /api/v1/fulfillment/fulfillable	Check stock availability
GET /api/v1/fulfillment/lots	List lot inventory
GET /api/v1/fulfillment/orders/{id}	Track a fulfillment
POST /api/v1/fulfillment/costs/order	Estimate fulfillment costs

Shipping Integration

Manage shipping for orders you ship yourself (non-fulfillment).

Recommended approach

1. Get quotes — When an order is ready to ship, request quotes via POST /api/v1/orders/{order}/shipping-quotes with parcel dimensions and weight.
2. Confirm a quote — Select the best quote and confirm it via POST /api/v1/shipping-quotes/{quote}/confirm. This generates a shipping label if using Ankorstore's label service.
3. Schedule pickup — For Ankorstore Label shipments, schedule a carrier pickup via POST /api/v1/orders/{order}/ship/schedule-pickup.

See Shipping for the full shipping flow including sequence diagrams.

Webhook-Driven Architecture

For the most responsive integration, build around webhooks rather than polling.

Recommended approach

1. Create an application — Your webhook subscriptions are tied to an OAuth application. List yours at GET /api/v1/applications.
2. Subscribe to events — Create a subscription with the events you care about:

   POST /api/v1/webhook-subscriptions
   

3. Verify signatures — Every webhook delivery includes an X-Ankorstore-Hmac-SHA256 header. Verify it using your application's signing secret. See Webhook Subscription for verification code examples.
4. Handle retries — Failed webhook deliveries are retried automatically. Design your endpoint to be idempotent.

Available events

See the Webhook Subscription page for the full list of available events and their payload structures.

Sync your product catalog and stock levels between your internal systems and Ankorstore.

Recommended approach

1. Initial catalog import — Use Catalog Integrations to batch-import products via the operations API. This handles create, update, and delete in bulk with async processing and callback notifications.
2. Ongoing stock sync — Keep stock levels in sync by updating product variant stock via PATCH /api/v1/product-variants/{productVariant}/stock whenever your inventory changes. For detailed stock visibility across locations, use the ASTRAL Stock State endpoint.
3. Price updates — Update product variant prices via PATCH /api/v1/product-variants/{productVariant}/prices.

Key endpoints

Endpoint	Purpose
POST /api/v1/catalog/integrations/operations	Create batch product operations
PATCH /api/v1/product-variants/{id}/stock	Update stock for a single variant
PATCH /api/v1/product-variants/{id}/prices	Update prices for a single variant
GET /api/v1/products	List your products

Integrate order processing with your order management system.

Recommended approach

1. Receive new orders — Subscribe to the order.brand_confirmed webhook event to receive instant notifications when new orders arrive, instead of polling.
2. Fetch order details — Retrieve the full order with GET /api/v1/master-orders/{id}?include=internalOrder to get all order lines, amounts, and shipping address.
3. Process the order — Transition the order through its lifecycle: confirm, ship, and track via the order and shipping endpoints.
4. Sync back to your systems — Use the order reference and masterOrderId fields to match Ankorstore orders with records in your OMS.

Key endpoints

Endpoint	Purpose
GET /api/v1/master-orders	List all orders with pagination
GET /api/v1/master-orders/{id}	Get a single order with includes
POST /api/v1/orders/{order}/-actions/transition	Accept/reject an order
POST /api/v1/orders/{order}/shipping-quotes	Get shipping quotes
POST /api/v1/shipping-quotes/{quote}/confirm	Confirm a shipping quote
POST /api/v1/webhook-subscriptions	Subscribe to order events

Order event webhooks

Event	When it fires
order.brand_confirmed	A new order is confirmed and ready for processing
order.shipped	The order has been shipped
order.received	The retailer has confirmed receipt
order.brand_paid	Payment has been transferred to the brand
order.cancelled	The order has been cancelled

Manage inventory at Ankorstore Fulfillment Centers and track fulfillments.

Recommended approach

1. Send inventory — Create replenishments via POST /api/v1/fulfillment/replenishments to declare incoming stock, then update the status to confirmed when ready.
2. Monitor stock — Check fulfillable stock with GET /api/v1/fulfillment/fulfillable and lot-level inventory with GET /api/v1/fulfillment/lots. For detailed multi-location stock data, use the ASTRAL API.
3. Track fulfillments — When orders are fulfilled, track their progress via GET /api/v1/fulfillment/orders/{id}?include=statusUpdates.
4. Estimate costs — Before committing to fulfillment, get cost estimates via POST /api/v1/fulfillment/costs/order.

Key endpoints

Endpoint	Purpose
POST /api/v1/fulfillment/replenishments	Declare incoming stock
GET /api/v1/fulfillment/fulfillable	Check stock availability
GET /api/v1/fulfillment/lots	List lot inventory
GET /api/v1/fulfillment/orders/{id}	Track a fulfillment
POST /api/v1/fulfillment/costs/order	Estimate fulfillment costs

Manage shipping for orders you ship yourself (non-fulfillment).

Recommended approach

1. Get quotes — When an order is ready to ship, request quotes via POST /api/v1/orders/{order}/shipping-quotes with parcel dimensions and weight.
2. Confirm a quote — Select the best quote and confirm it via POST /api/v1/shipping-quotes/{quote}/confirm. This generates a shipping label if using Ankorstore's label service.
3. Schedule pickup — For Ankorstore Label shipments, schedule a carrier pickup via POST /api/v1/orders/{order}/ship/schedule-pickup.

See Shipping for the full shipping flow including sequence diagrams.

For the most responsive integration, build around webhooks rather than polling.

Recommended approach

1. Create an application — Your webhook subscriptions are tied to an OAuth application. List yours at GET /api/v1/applications.
2. Subscribe to events — Create a subscription with the events you care about:

   POST /api/v1/webhook-subscriptions
   

3. Verify signatures — Every webhook delivery includes an X-Ankorstore-Hmac-SHA256 header. Verify it using your application's signing secret. See Webhook Subscription for verification code examples.
4. Handle retries — Failed webhook deliveries are retried automatically. Design your endpoint to be idempotent.

Available events

See the Webhook Subscription page for the full list of available events and their payload structures.

ℹ️ Ankorstore provides a mechanism of webhook notifications to notify you of events that happen on the platform.

Subscribing

There are two ways to manage your webhook subscription on the platform:

1. Via UI in your Ankorstore account. You can find this functionality in the Private Apps tab of the Integrations section.
2. Directly via API. Find more details in the dedicated Webhoooks section of API specification.

Format

The webhook payload sent is the same as the resource object provided by the API. For example, if an order.* webhook is fired the resource will be OrderResource.

The only difference is that within the top level meta object you will receive an event object with details of the webhook which will look like this:

POST https://your-webhook-url.com/webhooks/handle

{
  "meta": {
    "event": {
      "id": "1ecdb3d8-4cc7-64b0-81e2-0242ac140007",
      "applicationId": "1ecd6935-c442-6b2c-a36b-0242ac120008",
      "type": "order.brand_accepted",
      "timestamp": 1653381780
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "data": {}
}

Events

Our currently supported events are:

• order.brand_created - A new order is created for the brand
• order.brand_accepted - Brand accepts the order
• order.brand_rejected - Brand rejects the order
• order.billing_address_updated - Billing address is updated
• order.shipping_address_updated - Shipping address is updated
• order.shipping_labels_generated - When shipping with Ankorstore
• order.shipped - Fired by either shipping with custom or with Ankorstore
• order.shipment_received - Retailer confirms reception of the order
• order.shipment_refused - Retailer refuses the order
• order.brand_paid - Ankorstore pays the brand for the order
• order.cancelled - Order is cancelled
• order.brand_accepted_reverted - Reverted Brand accepting the order
• order.shipping_labels_generated_reverted - Reverted shipment labels generation, when shipping with Ankorstore
• external_order.created - A new external order is created for the brand
• external_order.awaiting_fulfillment - Order is waiting for fulfillment
• external_order.cancelled - Order is cancelled
• external_order.shipped - Order shipped from the warehouse
• external_order.arrived - Order is arrived and completed

Note: When External Order is created webhook external_order.created is fired and at same time fulfillment is requested which means external_order.awaiting_fulfillment is also fired. Due to async nature of webhook when you receive these webhooks most likely order status is awaiting_fulfillment for external_order.created webhook too.

Signature

Our webhooks provide a signature so you can verify the payload hasn't been tampered with. This signature can be found on the header signature.

This is how the signature is calculated:

/**
 * @var string $payload JSON payload of the received webhook
 * @var string $secret Secret key which can be found in the particular webhook subscription settings
 * @var string $signature Calculated signature, to be compared with the value in the request header
 */
$signature = hash_hmac('sha256', $payload, $secret);

Here is the same verification in Node.js:

const crypto = require('crypto');

/**
 * @param {string} payload - Raw JSON body of the received webhook
 * @param {string} secret - Secret key from your webhook subscription settings
 * @param {string} headerSignature - Value of the "signature" request header
 * @returns {boolean} Whether the signature is valid
 */
function verifyWebhookSignature(payload, secret, headerSignature) {
  const calculated = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(calculated),
    Buffer.from(headerSignature)
  );
}

And in Python:

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, secret: str, header_signature: str) -> bool:
    """
    :param payload: Raw JSON body of the received webhook (bytes)
    :param secret: Secret key from your webhook subscription settings
    :param header_signature: Value of the "signature" request header
    :return: Whether the signature is valid
    """
    calculated = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(calculated, header_signature)

You can calculate the webhook's signature and compare it to the one present in the request header.

Note: the secret key needed for verification webhook signature is not the same as the API secret key. Each webhook subscription has its own secret key which can be found in the particular webhook subscription settings.

Retries

If the response status code is not a 2xx then we will retry the webhook for 5 attempts with an exponential backoff.

ℹ️ This guide explains how the Ankorstore API communicates errors and how to handle them in your integration.

The API follows the JSON:API error specification. Every error response contains an errors array with one or more error objects:

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Content",
      "detail": "The field is required.",
      "source": {
        "pointer": "data.attributes.field"
      }
    }
  ]
}

Error object fields

Field	Type	Description
status	string	HTTP status code (e.g., "422")
title	string	Short human-readable summary of the problem
detail	string	Specific explanation of what went wrong
code	string	Application-specific error code (e.g., ORDER_ACTION_REJECT_FAILED)
source.pointer	string	JSON Pointer to the field that caused the error (e.g., data.attributes.email)
meta	object	Additional metadata about the error when available

Client errors

Status	Meaning	When you see it
400 Bad Request	The request is malformed or missing required parameters	Invalid JSON, missing required headers
401 Unauthorized	Authentication failed or token has expired	Expired or missing Bearer token
403 Forbidden	You do not have permission to access this resource	Accessing another brand's resources
404 Not Found	The requested resource does not exist	Invalid resource ID or deleted resource
406 Not Acceptable	The Accept header is not application/vnd.api+json	Missing or incorrect Accept header
409 Conflict	The action conflicts with the current resource state	Trying to accept an already-shipped order
415 Unsupported Media Type	The Content-Type header is not application/vnd.api+json	Missing or incorrect Content-Type on POST/PATCH
422 Unprocessable Entity	The request body is valid JSON but contains invalid data	Validation errors on fields
429 Too Many Requests	You have exceeded the rate limit	See Rate Limiting

Server errors

Status	Meaning	What to do
500 Internal Server Error	Something went wrong on our side	Retry with backoff (see below)

Not all errors are retryable. Use this table to decide how to handle each category:

Status	Retryable?	Recommended action
400, 403, 404, 406, 415, 422	No	Fix the request. These indicate a problem with your code or data.
401	Once	Re-authenticate by fetching a new token, then retry the request.
409	Conditional	Re-fetch the resource state and decide whether the action still applies.
429	Yes	Wait for the duration specified in the Retry-After header, then retry.
500	Yes	Retry with exponential backoff.

Exponential backoff

For retryable errors, use exponential backoff to avoid overloading the API:

Attempt 1: wait 1 second
Attempt 2: wait 2 seconds
Attempt 3: wait 4 seconds
Attempt 4: wait 8 seconds
Attempt 5: wait 16 seconds (max)

Add a small random jitter (e.g., 0–500 ms) to each wait time to prevent multiple clients from retrying in lockstep. Stop retrying after 5 attempts and log the failure for investigation.

Rate limit handling

When you receive a 429 Too Many Requests response, the API includes headers to help you recover:

• Retry-After — Number of seconds to wait before your next request
• X-RateLimit-Reset — Unix timestamp when your rate limit window resets

Always respect the Retry-After value rather than using a fixed delay.

Many operations in the Ankorstore API are idempotent, meaning you can safely retry them without causing unintended side effects:

• GET requests are always safe to retry.
• PATCH requests that set a field to a specific value (e.g., updating stock to 42) are idempotent.
• POST requests are typically idempotent when you supply an entity UUID in the request body (e.g., data.id). If the resource with that ID already exists, the API returns the existing resource rather than creating a duplicate. This makes it safe to retry POST requests after a network failure as long as you provide the same UUID.

Safe retry pattern

1. Generate a UUID client-side — Before creating a resource, generate a UUID and include it as data.id in your request body. If the request fails due to a network error, retry with the same UUID.
2. Handle 409 gracefully — If you receive a 409 Conflict, the resource may have already moved to the desired state. Re-fetch it and verify.
3. Use webhooks as source of truth — Rather than polling and retrying, subscribe to webhooks for state change confirmations. See Webhook Subscription.

Handling a validation error (422)

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Content",
      "detail": "The quantity must be at least 1.",
      "source": { "pointer": "data.attributes.quantity" }
    },
    {
      "status": "422",
      "title": "Unprocessable Content",
      "detail": "The sku field is required.",
      "source": { "pointer": "data.attributes.sku" }
    }
  ]
}

Use source.pointer to map each error back to the relevant field in your request.

Handling a state conflict (409)

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "code": "ORDER_ACTION_REJECT_FAILED",
      "detail": "Order cannot be rejected from this state",
      "status": "409"
    }
  ]
}

The code field tells you the specific business rule that was violated. Re-fetch the order to check its current state before deciding on your next action.

Handling an expired token (401)

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

Request a new access token via POST /oauth/token and retry the original request. See Authentication for token management best practices.

• Log error responses — Store the full error response body (including code, detail, and source) for debugging. Include the request method, URL, and your internal correlation ID.
• Do not retry blindly — Check the status code before deciding whether to retry. Retrying a 422 wastes resources and never succeeds.
• Surface actionable messages — Use the detail field to display meaningful messages to your users. Fall back to title if detail is not present.
• Monitor 429 responses — Frequent rate limiting indicates your integration needs optimization. Consider caching responses and using webhooks instead of polling.
• Handle unknown errors gracefully — If you encounter a status code not listed above, treat 4xx as non-retryable and 5xx as retryable with backoff.

ℹ️ This page tracks notable changes to the Ankorstore Public API, including new features, improvements, deprecations, and breaking changes.

We recommend checking this page regularly to stay informed about API updates that may affect your integration.

February 2026

Documentation improvements

• Added Getting Started guide for first-time integrators
• Added Integration Scenarios page with recommended patterns for catalog sync, order management, fulfillment, and shipping
• Added Error Handling guide with retry strategies and idempotency guidance
• Expanded Webhook Subscription with Node.js and Python signature verification examples
• Expanded Authentication with token refresh strategy and security best practices
• Expanded Testing API with sandbox limitations and mock server guidance
• Added API Versioning policy to "How to work with API"
• Expanded description pages for OrderPay, User, General, and Fulfillment API groups
• Added response examples to Master Orders and OrderPay endpoint specs

API changes

• Added available-apis overview describing all API groups including ASTRAL

Q4 2025

• Upgraded Redocly documentation renderer
• Introduced Fulfillment endpoints for orders, lots, replenishments, and cost estimation

---

ℹ️ This section contains some hints and examples on how to simplify and speed up API integration process by using our public sandbox environment for testing API.

A mock server is also available as a docker image: ankorstore/api-mock-server

docker run --rm -t -p 1080:1080 ankorstore/api-mock-server

How to get a public sandbox account?

Already live on Ankorstore?

If your Brand is already live on Ankorstore, please try logging in with your credentials on Ankorstore public sandbox. If it does not work, please contact your Ankorstore Brand Development Manager and request an account. Once the account is created, you will receive an email with the sandbox link to set up your credentials.

Not on Ankorstore yet?

In case you are not yet live with Ankorstore, please contact our Sales Team.

Using the public sandbox environment

When you test the order management flow through the API you may want to create some dummy orders to test the API integration, to do that you can create any number of test retailer accounts on the sandbox in order to create test orders for your brand. When placing an order you can pay using the test Stripe credit card credentials below:

Card Number: 4242 4242 4242 4242 Expiry: 04/42 CVV: 424

Creating test data

Our public sandbox environment provides some endpoints to more easily generate test data.

See the available endpoints here.

Sandbox Limitations

The public sandbox environment mirrors production functionality, but with some intentional differences to support safe testing:

What works the same as production:

• All API endpoints and response formats
• OAuth2 authentication flow
• Webhook delivery (configure a publicly-accessible HTTPS endpoint)
• Rate limiting (same limits as production)
• Validation rules and business logic

Differences from production:

• No real payments — Stripe is in test mode. Use the test card 4242 4242 4242 4242 for payments.
• No real emails — The sandbox does not send transactional emails to protect test accounts from spam. You can inspect email content via the admin interface if needed.
• Isolated data — Sandbox and production databases are completely separate. Data created in the sandbox does not appear in production, and vice versa.
• Performance — The sandbox may be slower than production and has lower resource allocation. Do not use sandbox performance metrics for production capacity planning.

Feature parity:

The sandbox is updated alongside production releases, so new API features are available in both environments simultaneously. However, some internal-only features or beta functionality may not be enabled in the sandbox. If you encounter unexpected behavior, contact Ankorstore Support.

Data Reset and Cleanup

The sandbox environment is shared by all integrators, and test data accumulates over time. To maintain a clean testing environment:

Manual cleanup:

• Delete test products, orders, and other resources via the API when you are done testing.
• Use the DELETE endpoints where available to remove resources you created.

Requesting a data reset:

If you need a complete reset of your brand's sandbox data, contact Ankorstore Support with:

• Your sandbox brand name or ID
• Confirmation that you want all sandbox data deleted

This process is manual and may take 1–2 business days. Plan ahead if you need a clean slate for integration testing or demos.

Mock Server

For fully offline testing or CI/CD pipelines, use the official mock server Docker image:

docker run --rm -t -p 1080:1080 ankorstore/api-mock-server

The mock server returns static example responses for all documented endpoints. It does not persist data or enforce business logic, but it is useful for:

• Testing your client code without network dependencies
• Validating request and response serialization
• Running integration tests in CI/CD without sandbox credentials

Note: The mock server uses example data from the OpenAPI specification. If endpoint examples are missing or outdated, the mock responses may not reflect real-world data. Always validate your integration against the live sandbox environment before going to production.

Ankorstore provides access to its API (Application Programming Interface) for the purpose of enabling brands to integrate with our services to ease their workflow. We encourage the use of our API in accordance with the following fair use principles:

1. Respect for Rate Limits: To ensure fair access for all users, we enforce rate limits on API requests. Developers are encouraged to adhere to these limits and implement appropriate strategies, such as utilising webhooks, caching, etc. to minimize unnecessary requests and reduce load on our servers.

2. Data Integrity and Privacy: Developers must handle any data obtained through our API with care, respecting user privacy and maintaining data integrity. Any misuse or unauthorized access to user data is strictly prohibited and may result in termination of API access.

3. Compliance with Terms of Service: All usage of our API is subject to our Terms of Service. Developers are expected to review and comply with these terms, which outline the rights and responsibilities associated with using our API.

By accessing or using our API, you agree to abide by these fair use principles and any additional terms and conditions specified in our documentation or Terms of Service. Ankorstore reserves the right to monitor API usage and take appropriate action to enforce these guidelines, including limiting or revoking access to the API for users who violate them.

For questions or concerns regarding API usage or these fair use principles, please contact Ankorstore Support.

ℹ️ This section contains general-purpose endpoints that are transversal to the system. These endpoints provide reference data useful across different integration scenarios.

The currency rates endpoint returns the latest exchange rates used by the Ankorstore platform.

⚠️ This endpoint is public and does not require authentication.

[GET] /api/v1/currencies/rates/latest

Each rate entry contains:

• fromCurrency - The source currency code (e.g., "USD")
• toCurrency - The target currency code (e.g., "EUR")
• rate - The exchange rate as a decimal number
• date - The date of the rate

This is useful when your integration needs to display prices in multiple currencies or reconcile amounts across different currency zones.

ℹ️ This section describes the API endpoints for retrieving user and platform configuration.

The user configuration endpoints return locale and currency settings for the authenticated user. This is useful for adapting your integration to the user's preferences.

Current User

Retrieve the configuration for the currently authenticated user:

[GET] /api/v1/me/config

Returns:

• currency - The user's preferred currency (e.g., "EUR", "GBP")
• country - The user's country code (e.g., "FR", "DE")
• browserId - A browser-session identifier

Specific User

You can also retrieve configuration for a specific user by UUID:

[GET] /api/v1/users/{id}/config

The platform configuration endpoint returns global settings that apply to all users:

[GET] /api/v1/platform/config

Returns:

• cdn - The CDN base URL for loading assets (e.g., product images)
• stripePublicKey - The Stripe public key, needed if your integration handles payment flows client-side

ℹ️ This section describes the API endpoints that you can use to manage your catalog resources, such as products, product variants etc.

Here you will find information about the product resource and its sub-resources. If you need further information please refer to the API specification.

Including Product Variants

When retrieving the individual product via the API, you may pass an ?include=productVariants query parameter that will return associated product variants inside the included root level object.

Important Fields within Product Resource

If the field contains no data, it will be null.

This API allows you to manage your product variants stock for the marketplace in both single- and bulk-operation mode. There are 2 opposite options available for the stock update requests - set an explicit product quantity or mark the corresponding product as "always in stock".

Stock statuses

Stock for the marketplace can be in one of two states. It can be available to order on the marketplace, or reserved for an order that has been submitted, but not yet shipped. Added together, these quantities make up the onHand state, which reflects the total quantity of the product variant "on hand" at your storage location(s).

⚠️ Unless specified otherwise, stockQuantity used in the following APIs refers to onHand quantity

See also Stock State for more general information about stock states used in the Stock Tracking APIs.

Example

• 100 units of the product variant X are stock at your location (onHand).
• 30 units of product variant X are reserved for Ankorstore orders that have not yet been shipped.
• Then 70 units of product variant X are available to order on the marketplace.

Now consider you produce 50 more units of product variant X, and sell 27 units on another marketplace. Your input for the stock update API would be:

// 100 + 50 - 27 = 133
"stockQuantity": 123

Set product variant stock explicit quantity

To set an explicit quantity for the particular product variant, you should specify the amount in the payload. In case if the target product variant was previously marked as "always in stock", this option will be disabled and the stock will be set to given value.

Example of the payload to set a product variant stock to the given value (single-operation mode):

PATCH /api/v1/product-variants/1ed18988-6651-610e-8223-aa5cd9844f96/stock

{
  "data": {
    "attributes": {
      "stockQuantity": 123
    }
  }
}

More details can be found in the endpoint specification

Set product variant as "always in stock"

To mark a particular product variant as "always in stock" and do not care about the stock amounts, you should include a flag isAlwaysInStock into the request payload. In case if the target product variant had explicit stock amount set previously, it will be reset.

Example of the payload to set a product variant stock to the given value (single-operation mode):

PATCH /api/v1/product-variants/1ed18988-6651-610e-8223-aa5cd9844f96/stock

{
  "data": {
    "attributes": {
      "isAlwaysInStock": true
    }
  }
}

More details can be found in the endpoint specification

Update stocks of multiple product variants in single request (bulk-operation mode)

This API allows to update stocks of multiple product variants in single request. There is a specific endpoint which accepts up to 50 operations per request. Validation, business rules and payload of each operation is identical to the single-operation mode, described above.

Example of the payload to update stocks of multiple product variants in single request:

POST /api/v1/operations

{
  "atomic:operations": [
    {
      "op": "update",
      "data": {
        "type": "productVariants",
        "id": "1ed18988-3253-610e-8223-aa5cd9844001",
        "attributes": {
          "isAlwaysInStock": true
        }
      }
    },
    {
      "op": "update",
      "data": {
        "type": "productVariants",
        "id": "1ed18988-6651-610e-8223-aa5cd9844f96",
        "attributes": {
          "stockQuantity": 123
        }
      }
    }
  ]
}

More details can be found in the endpoint specification

The catalogue integration process relies on the concept of operations. An operation is a batch of records representing the products to create, update or delete. The completion state of an operation depends on the execution result for every record it contains. It means an operation might fail without necessarily stopping or marking the whole operation as failed (this particular state is defined as “Partially failed”).

• Operations can be of type import, update or delete.
• Only one open operation (not yet started) is allowed at a time.
• Only one operation can be performed (started) at a time.
  • Any subsequent operation will be queued with status pending until previous one has finished processing.
  • If no previous operation is being processed, operation will start processing right away.

Operation Statuses

The status attribute represents the current state of the operation, below is a table that describes each state:

Status	Description
created	The operation was created and not yet started. At this stage, the operation is considered open and products can still be added to the batch.
skipped	The operation is empty and was skipped (No action required). When an operation is skipped, an empty report is generated and the callback URL is called to notify operation is completed.
started	The operation started and is processing.
pending	Operation is waiting for its turn on the processing queue. The operation could not be started because another one was being processed.
succeeded	All products were successfully processed.
failed	All products failed to be processed.
partially_failed	Not all products were successfully processed.

The complete workflow for an operation occurs in 3 stages: operation creation, operation processing and reporting. The following diagram illustrates these stages and how they are chained.

%%{init: {"flowchart": {"curve":"basis", "htmlLabels":false, "diagramPadding":24 } } }%%
graph LR

created("Operation Created")
start("Start Processing")
started("Processing\nStarted")
succeeded(Succeeded):::success
skipped("Processing Skipped"):::success
pending("Operation pending")
failed(Failed):::failure
partial(Partially Failed):::warning
report("Report\nGenerated")
notified(Callback Sent)

subgraph creating[Creating Operation]
created -- Add Products --> created
end

created -- Start Operation --> Start{?}
Start -->|"Another Operation execution in progress"| pending
Start --->|"No other Operation in progress"| start --> E{?}
E -->|"Batch.size > 0"| processing
E --->|"Batch is empty"| skipped

subgraph processing[Processing Operation]
direction LR
started --> succeeded
started --> partial
started --> failed
end

succeeded --> operationCompletedActions
partial --> operationCompletedActions
failed --> operationCompletedActions

subgraph reporting[Reporting]
report -- Notify --> notified
end

subgraph triggerNext[Trigger next pending Operation]
end

subgraph operationCompletedActions[Post-Complete Operation Actions]
reporting
triggerNext
end

pending -- Wait for previous Operation to finish execution --> start

skipped -- Generate empty report --> operationCompletedActions

classDef default stroke:#4b475f,stroke-width:1px,fill:#ffffff,color:#4b475f
classDef success stroke:#1aae9f,stroke-width:1px,fill:#cfeeeb,color:#293845
classDef failure stroke:#d3455b,stroke-width:1px,fill:#f6d8dd,color:#293845
classDef warning stroke:#f7c325,stroke-width:1px,fill:#fdf2d1,color:#293845
linkStyle default stroke:#788896,stroke-width:1px,fill:transparent

Creating an Operation

The full flow of creating a complete operation consists in two steps:

1. Create a new operation

Send a POST request to /api/v1/catalog/integrations/operations

Example request:

{
    "data": {
        "type": "catalog-integration-operation",
        "attributes": {
            "source": "shopify",
            "callbackUrl": "https://callback.url/called/after/processing",
            "operationType": "import"
        }
    }
}

• At this point the new operation has been created and waiting to receive products data
• Operation ID will be returned in the response payload

2. Add product data to operation

Send a POST request to /api/v1/catalog/integrations/operations/{operationId}/products

Products can be added only to operations with status created.

If operation has been started already (having any of started, pending, skipped, succeeded, partially_failed, failed, cancelled status), the request will fail with a 403 Forbidden status code.

Example request:

{
    "products": [
        {
            "id": "B006GWO5WK",
            "type": "catalog-integration-product",
            "attributes": {
                "external_id": "B006GWO5WK",
                "name": "Example product"
                // ...
            }
        }
    ]
}

You can perform as many requests as needed to append product data during this stage.

Operation Processing

In order to start processing the operation, you have to send a PATCH request to /api/v1/catalog/integrations/operations/{operationId} with the expected operation status (i.e. “started”).

If there is any other operation being executed at that time, the operation will be enqueued to be processed with the status pending and will be started as soon as it gets a free slot in the queue. Otherwise, the operation will be started right away.

Example request:

{
    "data": {
        "id": "90567710-de47-49e4-8536-aab80c1a469c",
        "type": "catalog-integration-operation",
        "attributes": {
            "status": "started"
        }
    }
}

Execution Report

When an operation completes, an execution report is generated. It provides the execution results (success or failure) for every product of the operation.

You can access this report by reading from the following endpoint.

GET /api/v1/catalog/integrations/operations/{operationId}/results

Callbacks enable you to get notified when events occur in the operation process. For example, you can configure a callback to notify you when the operation is completed. The notification is sent via an HTTP request to the URL you specify in the operation settings.

Callbacks can be used to trigger automated actions in your integration.

Supported events

You can find here below the complete list of all the topics {{resource}}.{{event}} you can monitor:

Topic	Trigger
catalog-integration-operation.completed	An operation reaches a completed state such as Success, Failed, or Partially Failed
catalog-integration-operation.cancelled	An operation was cancelled. This event is triggered when an operation processing is Skipped (i.e. the operation batch is empty and no action is required).

Event schema

A callback event is represented as a JSON object and has the following properties:

• event — the name of the event that occurred (e.g. “completed”)
• topic — the event category represented as a unique identifier of the event type. The topic is defined as a concatenation of the resource and event names {$.data.type}.{$.event}, e.g. “catalog-integration-operation.completed”. You might use this topic as a partition key to distribute the callback events you receive to separate queues or pools of workers to process the callbacks asynchronously.
• occurredAt — the date and time when the event occurred
• data — the JSON:API resource describing the state of the entity which triggered the callback

A callback event is delivered as a POST request to your endpoint. The following payload represents the notification request that is triggered when an operation successfully completes:

{
    "event": "completed",
    "topic": "catalog-integration-operation.completed",
    "occurredAt": "2024-03-21T13:42:54+00:00",
    "data": {
        "id": "90567710-de47-49e4-8536-aab80c1a469c",
        "type": "catalog-integration-operation",
        "attributes": {
            // ...
            "status": "succeeded",
            "createdAt": "2024-03-21T13:13:03+00:00",
            "startedAt": "2024-03-21T13:19:32+00:00",
            "completedAt": "2024-03-21T13:42:54+00:00"
            // ...
        }
    }
}

Handling callbacks

The endpoint listening for callbacks has 3 seconds to respond with a 2xx (usually 200) response code, acknowledging a successful delivery. If the request times out or gets a response with a status code other than 2xx, it is considered failed.

Testing callback

A number of websites, such as https://webhook.site and https://requestbin.com, provide free URLs that can be used to test callbacks. Simply create a URL on one of these sites, then configure your webhook to use it. These sites allow you to see the details of the request sent to them by the callback service.

In addition, the Ngrok service (https://ngrok.com) allows you to tunnel callback requests to a non-publicly accessible server, enabling you to test your callback-handling code before making it public.

Operations and Drafts behaviour

Type	Behaviour
import	When executing an import operation existing drafts will be cleaned and new ones will be created if any of the products attached to the operation has any validation issue.
update	Will not have any impact on existing drafts.
delete	Will not have any impact on existing drafts.